-- -------------------------------------------------------------------------
-- Lib/helpers.lua
-- Common Helper Functions (减少重复代码)
-- -------------------------------------------------------------------------

local helpers = {}

-- [Translation Cache]
local cached_T = nil

--- 翻译函数 (统一版本)
--- @param text string 要翻译的文本
--- @return string 翻译后的文本
function helpers.T(text)
    if cached_T then return cached_T(text) end
    if _G._T then
        cached_T = _G._T
        return cached_T(text)
    end
    return text
end

--- 显示通知 (统一版本)
--- @param ui table|nil UI 模块引用
--- @param text string 通知文本
--- @param type_str string|nil 通知类型 (默认 "Info")
function helpers.show_toast(ui, text, type_str)
    if ui and ui.notify then
        ui.notify(text, type_str or "Info")
    elseif util and util.toast then
        util.toast(text)
    end
end

--- 创建带 lang 回退的翻译函数
--- @param lang table|nil 语言模块引用
--- @return function 翻译函数
function helpers.create_T(lang)
    local cached = nil
    return function(text)
        if cached then return cached(text) end
        if _G and _G._T then
            cached = _G._T
            return cached(text)
        end
        if lang then
            if lang.get then return lang.get(text) end
            if lang.get_text then return lang.get_text(text) end
        end
        return text
    end
end

--- 安全调用函数
--- @param fn function|nil 要调用的函数
--- @vararg any 函数参数
--- @return any|nil 调用结果或 nil
function helpers.safe_call(fn, ...)
    if not fn then return nil end
    local ok, result = pcall(fn, ...)
    if ok then return result end
    return nil
end

--- 检查是否为有效句柄
--- @param h any 句柄值
--- @return boolean
function helpers.is_valid_handle(h)
    return type(h) == "number" and h ~= 0
end

return helpers
